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Chapter 1 Introduction 


1.1 BASE System Software and Standard Options 


The system software for Processor Modules of Advant Controller 100 Series usually comprises 
the BASE system software shipped on a 3.5” diskette, labelled 


Advant Controller xxx 
BASE System Software 
Version ACxxxCTBASE*x.y/z 


(xxx denotes the controller type, x.y/z is the version identification), 
and several so called “standard options”. 


The BASE system software provides the basic functionality of an Advant Controller 100 Series 
whereas the standard options enhance the system’s functionality. Such options are for instance: 


° OPT 1: Extended PC Element Set 

° OPT2: MVI Handling 

° OPT3: Event Handling 

° OPT4: Modbus I protocol 

* OPTS: RCOM driver! 

Note that each option includes a version identification not indicated above. 


Options can either be delivered on a 3.5” diskette and must ordered separately in the price list or 
they are already bundled with the BASE system software. All standard options are included in 
the AMPL PC and DB Libraries, thus supported by AMPL Control Configuration (ACC) and 
Advant Station 100 Series Engineering Station (AS 100ES). 


1.2 Extensions, Add-On Options 
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Although those “standard options” often bring great enhancement to the functionality, the need 
for customer-specific PC elements may arise to match business unit specific applications. 


An extension—in this context—is a PC element or a group of PC elements embraced from a 
library that can be loaded to the controller to “extend” its capabilities. If description files for 
AMPL Control Configuration are added, we rather speak of customer specific add-on options. 


In contrast to standard options, these add-on options are usually distributed on a diskette 
containing: 


° the option loader, 
° the binary image to be loaded to the controller, 


° a batch file for loading the image file 
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° several description files for AMPL Control Configuration plus 
° documentation. 


The customer is able to apply the option to Advant Controller and AMPL Control Configuration 
himself. 


The loader “adds” the code to the Advant Controller’s system software during run-time; the 
advantage is, that there is no need to modify the system software itself. Thereby, the only 
limitation for the number of add-on options is the available system FPROM memory of the 
processor module, respectively it’s RAM size. 


The description files for AMPL Control Configuration are read and compiled by the Setup Add- 
ons Utility on the PC (for instance Advant Station 100 Series Engineering Station). 


An Add-on option may also be distributed together with complete PC program applications that 
make use of PC elements that are included in the option. 


1.3 Scope of This Manual 
This manual 
° gives an overview about add-on options, 
° describes the PC element building process and 


° guides the developer to his distributable extension diskette. 


1.4 User Characteristics 


Besides knowledge of programming in assembler or (ANSI-) C, the user should be familiar with 
ABB Advant technology, especially: 


° System software programming for embedded systems, 
° ABB AMPL programming, 


° Usage of Advant Station 100 Series Engineering Station (AS 100ES) and Add-On 
Libraries. 
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1.5 How to Use This Book 


This book is organized into chapters and sections as shown in Figure 1-1. 


Chapter 
a 
System ‘“« Appendix 
Software a Said Sample 
; Extensions Development ow to Bui Programmer’s Option 
Introduction Disk Environment an Option Reference BOWER? 
BASE System Contents of Hardware Introduction Introduction 
saliwale anal ioneNe Software Building and Data Types 
Perea oo Target peaaiig:an Standard System 
-On ion 
‘ Pee”'STemplates Operating si Library Definitions 
cope o uildin 
This Manual rll Option eystem Option Files Standard 
POWER C-Functions 
User Files for AMPL 
Characteristics ee : System Software 
How to Use omiguration Functions 
This Book Contents of 
Conventions eee 
Related 
Loading the Option 
pecumentavan to the Controller = 
fe Adding the Option Section 
to ACC 
Terminology 


Figure 1-1. Manual Organization Structure 


1.6 Conventions 


The following conventions are used throughout this manual for the presentation of material: 


° The words in proper names of screen elements (for example, the title in the title bar of a 
window, the label for a field of a dialog box) are initially capitalized. 


° The names of keyboard keys are boldfaced. 


— Initial capital letters are used for the name of a keyboard key if it is labeled on the 
keyboard. For example, the Return key or <Return>. 


— Lowercase letters are used for the name of a keyboard key that is not labeled on the 
keyboard. For example, the space bar, comma key, and so on. 


—  Indescriptions, the word “key” is used in conjunction with its name. For example, 
pressing the Return key initiates the process. 


— In tables and procedures, angle brackets replace the word “key.” For example, press 
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<Return>. 


— A dash is used to indicate that you must simultaneously press several keys. For 
example, <Ctrl-C> indicates that you must hold down the Control key while 
pressing the C key. 


— The phrase “press and release” is used to indicate that you sequentially press several 
keys. For example, to close a window, press and release <AIt>, and then <F4>. This 
indicates that you press and release the Alt key, and then you press and release the F4 
function key. 


° The names of push and toggle buttons are boldfaced. 


— Initial capital letters are used for the name of a push or toggle button labeled on the 
display. For example, the OK button. 


—  Indescriptions, tables and procedures, the word “button” is used in conjunction with 
its name. For example, pressing the OK button initiates the process. 


° The names of menus and menu items are boldfaced. 


— Initial capital letters are used for the name of menus listed in the menu bar. For 
example, the File menu. 


— Initial capital letters are used for the name of menu items. For example, to open a 
new window, choose New from the File menu. 


° System prompts/messages are shown in the Courier font, and user responses/input are in 
the boldfaced Courier font. For example, if you enter a value out of range, the following 
message is displayed: 


Entered value is not valid. The value must be 0-30. 


In a tutorial, you may be told to enter the string TIC132 in a field. The string is shown as 
follows in the procedure: 


TIC132 


1.7 Related Documentation 


Table 1-1 lists all documentation related to... 


Table 1-1. Related Documentation 


Title Description 
VRTX Velocity VRTX/OS 68K, RTL User’s Guide | This guide helps you using the run-time library 
50QDM0005 of VRTX OS. 
AMPL Control Configuration Setup Add-ons Describes how to design a target description 
Designer’s Guide (TED) file and how to add a new option to 
3BDS 000 610R401 AMPL Control Configuration (included on 
System Software Extension Disk). 
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Table 1-1. Related Documentation 


Title Description 
AMPL Control Configuration PC Element Describes how to design a PC element 
Description for Advant Controller 100 Series, description for AMPL Control Configuration 
Designer’s Guide (included on System Software Extension Disk). 
3BDS 000 617R101 
AMPL Configuration Advant Controller 100 Describes how to program Advant Controller 
Series, Reference Manual 100 Series in general. 
3BSE 009 626R401 
Function Chart Builder User’s Guide This guide describes how to work with FCB. 
3BSE 007 149R801 
AS 100 Series Engineering Station User’s Guide | This guide describes how to work with AS 100 
3BSE 007 117R501 ES. 


1.8 Release History 


Table 1-2. Release History 


Version Description 


7 Separate documents for Advant Controller 110 and Advant Controller 
70, 16-bit development environment: 


3BDS 005 029/B and 3BDS 003 340/B 


1.0 New version common for Advant Controller 100 Series, based on 
Windows NT 4.0 development environment. 


1.9 Terminology 


The following is a list of terms associated with creating system software extensions that you 
should be familiar with. 


Term Description 

AC 160, AC 110, AC 70, Abbreviation for controllers in Advant Controller 100 Series. 
etc. 

ACC Abbreviation for AMPL Control Configuration. 

APB Application Builder, part of AMPL Control Configuration. 
AMPL ABB Master Programming Language. 
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Term Description 

CONTRM Control Module 
This is an executable unit within the PC program 
application. 

CPU Central Processing Unit 

CRC Cyclic Redundancy Code Check 

DB Data Base 

FB Function Block (PC element or move block) 

FCB Function Chart Builder, part of AMPL Control Configuration. 

FPROM Electrically Programmable Read Only Memory (Flash 
PROM) 

LED Light Emitting Diode 

MC Microcontroller (e.g. Motorola MC68360) 

OS Operating System 

PC Programmable Control 

PLC Programmable Logic Controller 

PM Processor Module (board with CPU) 

PROM Programmable Read Only Memory 

RAM Random Access Memory 

RTC Real Time Clock 

SSW System Software 

SW Software 


VRTX Operating system kernel from Ready Systems 
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Chapter 2 System Software Extensions Diskette 


2.1 Contents of Diskette 
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The System Software Extensions diskette labelled 


Advant Controller 100 Series 
System Software Extensions 
Version SSWEXT* 1.0/0 

Art. no. 3BDS005613R1000 


contains a README.TXT and an a self-extracting ZIP-file named SSWEXT10.EXE. 
Executing SSWEXT10.EXE will extract the contents listed in Table 2-land Table 2-2 to an 
arbitrary directory on the hard disk of your PC (default is the TEMP directory). The diskette 
contains an assortment of all files—including this document—necessary to develop a customer 
specific option. 


Table 2-1. Contents of System Software Extension Disk 


File Description 

AC7OIL.LIB Interface library for Advant Controller 70, providing a version- 
independent link to the base system software and to the C runtime 
functions. 

AC110IL.LIB Interface library for Advant Controller 110, providing a version- 
independent link to the base system software and to the C runtime 
functions. 

AC160IL.LIB Interface library for Advant Controller 160, providing a version- 
independent link to the base system software and to the C runtime 
functions. 

AC7OIL.H C language include file, defines the prototypes for the library 


functions in AC 70. 


AC110IL.H C language include file, defines the prototypes for the library 
functions in AC 110. 


AC160IL.H C language include file, defines the prototypes for the library 
functions in AC 160. 


PC_SKELE.C A skeleton for a C language PC element. 


PC_SKELE.ASM |A skeleton for a assembler language PC element. 


MATH.H Include file for mathematical functions. 


STRING.H Include file for string functions. 


PCFRAME.ASM | Assembly language PC element frame 
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Table 2-1. Contents of System Software Extension Disk (Continued) 


File Description 


JNFB.INC Assembler include file for PC elements containing the instructions 
that jump to the successor element. 


IBUILD32.EXE Image builder, used to create a loadable option file (82-bit 
version). 


LOADER32.EXE_ | Image loader for loading the add-on option to Advant Controller 
(32-bit version). 


Table 2-2 lists the files in sub-directory “Example”: 


Table 2-2. Contents of System Software Extension Disk, Sub-directory “Example” 


File Description 
MAKEFILE MKS make file for add-on option POWER. 
POWER.BAT Batch file for loading option POWER. 
POWER.BLD Image Builder input file. 

POWER.C POWER PC element source file. 
POWER.CMD Linker command file. 

POWER.ODF Image Builder option definition file. 
POWER.PED POWER PC element definition file. 
POWER.TED POWER option target element description 


Table 2-3 lists the files in sub-directory “Doc”: 


Table 2-3. Contents of System Software Extension Disk, Sub-directory “Doc” 


File Description 


D003340.PDF This document in Adobe Acrobat Reader format. 


D000610.PDF AMPL Control Configuration Setup Add-ons Designer’s Guide in 
Adobe Acrobat Reader format. 


D000617.PDF AMPL Control Configuration PC Element Descriptions for Advant 
Controller 100 Series Designer’s Guide in Adobe Acrobat Reader 
format. 
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2.2.1 Compiler / Linker 


Assembler, compiler and linkers are not included on the diskette. To get highest compatibility 
with the system software, it is recommended to purchase the cross-development tools listed in 
Chapter 3.2 "Software" on page 3-13. 


2.2.2 Image Builder 


The Image Builder packs the compiled object code file(s) together with control directives taken 
from definition files. The resulting image file (extension IMG) can be loaded to Advant 
Controller using the Image Loader. 


The Image Builder is present as executable file IBUILD32.EXE (runs under Windows NT 4.0). 


Syntax: 
IBUILD32 <Image Builder Command File> 


The Image Builder command file (extension BLD) must contain general library definitions an a 
link to at least one option. For each bound option, two files must be present: an ASCTI text file 
describing the option (Add-on Option Definition File, extension ODF) and a Motorola S-record 
formatted file containing the option’s linked code (extension ABS). The latter one must contain 
the public symbols for initialization and main routines as defined for PC elements. 


To make handling of the command file easier, it is assumed that the option definition file has the 
same name as the code file, with the extension ODF and ABS, respectively. Hence, it is not 
necessary to specify both files in the Image Builder command file; it is sufficient to use the 
filename without extension, the Image Builder will add them itself. 


More about add-on library build files can be found in Chapter 4.2.2. "Image Builder Command 
File" on page 4-19 and about option definitions files in Chapter 4.3.2 "Option Definition File 
Syntax" on page 4-21. 


2.2.3 Image Loader 
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The Image Loader takes the image created by the Image Builder (extension IMG) and 
transmits its contents to the Processor Module where it is stored in the system Flash 
PROM. 


The Image Loader is present as executable file LOADER32.EXE (runs under Windows NT 
4.0). 


LOADER32.EXE may also be called on command line, but it is a tool with a GUI. It supports 
standard COM ports under Windows NT 4.0 and also allows deletion of libraries. 


Syntax: 
LOADER32.EXE <port> <options> <imagefile> 
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Table 2-4. Syntax of LOADER32.EXE 


<port> Meaning 
-p1 Use COM port 1 
-p2 Use COM port 2 
<options> Meaning 
-d Display debug messages (logging communication) 
-| Delete Library (availability depends on target version) 
<imagefile> Meaning 
name Load image file given by “name” 


It is also possible to call this executable with out parameters. If an image file is present in 
current working directory, this will be taken automatically. 


In addition, the program searches for the first free communication port and takes this one as 


default. 


The Image Loader takes the loadable image created by the Image Builder and transmits its 
contents to the CPU, where it is stored in the system Flash PROM. 
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Figure 2-1 shows how the memory map looks like after loading. 


Free Memory A 


Library Control Block 2 —_ 


Code of Option 2 


Add-on Control Block 2 <<, 


Code of Option 1 


Add-on Control Block 1 


Library Control Block 1 <—— 


System Software 


MainTable.FirstFree 0x200006 (_MainTable) 


0x200000 (FPROM start) 


Figure 2-1. Memory Map 


The global table MainTable contains a pointer to the first unused flash PROM location. The 
Option Installer first writes a library control block to this location, containing a pointer to the 
end of the new code, and data identifying the library. After that, the options themselves 
including their add-on control blocks are written. 


2.3 Templates 


To reduce possible mistakes in advance, template files have been added to the extension disk. 
PC element skeletons can be taken to create a new C or Assembler module. 


The example files also may serve as templates. 
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2.4 Sample Option “POWER” 


To introduce the user in options, the sample option “POWER” with PC element POWER is part 
of the System Software Extensions diskette. The files will be extracted by SSWEXT-EXE to 
sub-directory “Example”, see Table 2-2. 


The PC element simply calculates the power of the input value, but all necessary steps for 
creating additional PC elements are easy to show with this example. 


Thus, further explanations in this document will refer to this example. 
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Chapter 3 Development Environment 


3.1 Hardware 


When talking about required hardware, we must have in mind that it must fulfill the 
requirements of several software products: 


° System software cross development environment, 

° AMPL Control Configuration, runs on Advant Station 100 Series Engineering Station, 

° Advant Controller 100 Series System Software. 

The latter one requires a special hardware—the Processor Module (PM810, PM63x, PM64x). 


The two first issues require a PC with Windows NT 4.0 operating system. Minimum hardware 
requirement is: 


° Intel Pentium 90 MHz or equivalent 
° 32 MB memory 
° 100 MB free disk space 


° V.24 serial interface 


3.2 Software 


Software supplied by ABB Automation Products GmbH 

The executable files from the System Software Extension Diskette: 

° Image Builder for Windows NT 4.0: IBUILD32.EXE, version 4.0/1 or newer; 
° Image Loader for Windows NT 4.0: LOADER32.EXE, version 4.0/0 or newer; 


NOTE 


This descriptions in this document refer to the versions specified above. Using 
lower versions is not recommended since they may show different behavior and 
functionality. 


° AMPL Control Configuration (ACC) version 1.6 or higher. 
° AMPL PC and DB Libraries 1.2 or higher. 
Third Party Software 


NOTE 


The programs listed below are not part of the System Software Extension 
Diskette; you must purchase them separately. 
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Operating System: Microsoft Windows NT 4.0. 


For compiling and linking it is necessary to use the following development tools from 
Mentor Graphics (the version numbers show the lowest possible version). 


— MCC68K C-Compiler 4.5R (4.21 for DOS/Windows 3.1x) 
— ASM68K Assembler 7.1J (6.8F for DOS/Windows 3.1x) 
— LNK68K Linker/Loader 7.1J (6.8F for DOS/Windows 3.1x) 


For debug and/or test purposes, it is possible to use SIM68K from Mentor Graphics, that’s 
a PC based 68000 simulator program. 


3.3 Target Operating System 
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The operating system kernel of Advant Controller 100 Series is based on VRTX32 by Ready 
Systems. It includes 


a communication driver for communicating with the Engineering Station 
I/O software to access the peripheral modules 
diagnostic routines to ensure the integrity of the system 


a library of basic PC elements to build an application program 
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Chapter 4 How to Build an Option 


4.1 Introduction 


To get familiar with the option building process, a little bit of theory may make understanding 
options easier. 


Options are represented differently on Advant Controller and on AS 100ES, or more precise: 
AMPL Control Configuration (ACC). 


° In APML Control configuration we use target description files (*.TED) to describe each 
Advant Controller. A TED-file contains one or more options represented by PC element 
descriptions (*.PED) and/or DB element descriptions (*.DED). 


° On Advant Controller an add-on option is represented by the loadable image file 
(* IMG)— the option library— which itself is built out of one or more option files 
(*.ODF). 


As we do not have DB elements in our scope, everything melts down to describing and 
implementing PC elements. They are more or less shaping the options. PC elements must be 
identically described on both sides, Function Chart Builder and Advant Controller, but they are 
implemented and running on the Processor Module. 


4.1.1 Creating a PC Element 
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When you want to create a PC element, its functionality must be fully defined in advance like it 
is described in AMPL Control Configuration PC Element Description for Advant Controller 
100 Series, Designer’s Guide. 


Besides the description of the data processing functions, you must also describe the input and 
output terminals. 


With those I/O terminals being defined, you now can specify the Advant Controller 100 Series 

object code for the PC element (see Section 4.3.6.3, Object Code Structure). This object code is 
interpreted during run time to move the input and output values and to reserve—if necessary— 
historical value space. Historical values are used for permanent storage of data which is local to 
the PC element; e.g., the data buffer for a FIFO element. 


Additionally, you need to enter a type code. It specifies where the code of the PC element is to 
be found. It is filled into a structure located in one of the both skeletons provided on the System 
Software Extension Disk. 


Furthermore, this object code must be introduced to AMPL Control Configuration as described 
in AMPL Control Configuration Setup Add-ons Designer's Guide. 


The developer then fills the skeleton function bodies with the code needed to perform the data 
processing function of the PC element. 


After the code is implemented and possibly tested off-line with a debugger, such as the Microtec 
68000 simulator or the debugger of an PCDOS compiler, we need to specify the properties of 
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the PC element. Those properties include, among other things, the PC element’s type code. For 
more information, see Section 4.3.2, Option Definition File Syntax. 


This file is then combined with the translated source code to form a so-called loadable image. 
The loadable image may then be loaded to Advant Controller 100 Series with the LOADER32 
program. 


4.2 Building and Loading an Option Library 
On Advant Controller 100 Series an option library consists of at least two parts: 
1. _ the library header 
2. at least one option (consisting of at least one PC element) 


Following figure illustrates the organization in memory: 


Library 1 


Option 1 


Option 2 


Option 3 


Library 2 


Option 1 


Option 2 


Figure 4-1. Physical Organization of Libraries and Options 
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The entire collection of files involved in the option building process is shown in following 


figure: 
Ref 
.ABS ODF |—y|.BLD- 
File File File 


Image 
Builder 


Linker 


Com- 
mand 


Image 
Loader 


Y 


Target 


Figure 4-2. The Option Building Process 


Each option is represented by one or more C-source and header files. They are compiled and 
linked together to one absolute output file (*.ABS). Several options (ABS-files) are bound 
together by the Image Builder, which additionally requires one option definition file (*.ODF) 
per option and a library building file (*.BLD). 


The image file (*.IMG) as a result of the Image Builder then may be loaded to the target, using 
the option Image Loader. 


4.2.1 Structure 


An add-on library contains one or more options. An option is represented by the definition and 
code of one PC element. 
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The physical structure of a library looks as follows: 


System Software 


Library 1 Header 


Offset to next library 


Library Name & Version 
Additional Information 


Option 1 


Interface Library 
Option 2 


Interface Library 


Library 2 


Figure 4-3. Physical Structure of Libraries 


Each library has following characteristics: 


° The header, containing administrative data, has a size of 48 bytes. 
Most of the information is taken from the BLD-file supplied to the Image Builder. 


° It has a valid library name, e.g., “Debug Tool PC elements”. 
° It has a valid version, e.g. “1.0/0” that matches the version in PED-file. 


° A library is loaded to the end of the system software (or to the end of another, already 
existing, library). Therefor, a library’s position is not determined - it must be position 
independent. This is done by compiling and linking option’s code position independent. 


NOTE 


To save FPROM memory, it’s wise to embrace as much options as possible with 
one library. The library header information then only will be allocated once. 
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4.2.2 Image Builder Command File 


This file serves as input for the Image Builder executable (see Chapter 2.2.2 "Image Builder" 
on page 2-9, 


All items in the file must start with the “%” sign and end with “:”. 


Possible entries are defined in following table: 


Table 4-1. Image Builder Command File Syntax (Example) 


Item Data Format Example Format 
TARGET char [20] “AC 110% Name of the target: 
Quotes are required if string contains blanks. 
Tabs are not allowed. 
LIBNAME char [20] “POWER” Name of the library: 
Quotes are required if string contains blanks. 
Tabs are not allowed. 
LIBVERSION char [13] 1.0/2 Version of the library: 
Without white spaces. 
BIND POWER Name of the option: 
Without white spaces. 
COMMENT Any comment File comment, may be placed anywhere. 
Each line in file must be lead separately by this 
entry. 
TARGET 
Specifies the target, for which the library has been built, e.g. “AC 110”. The Image Loader 
performs a check against the target and denies download if this string does not match the string 
delivered by connected target. 
LIBNAME 
This string specifies the library’s name. It is the string that later on will be displayed on AS 
100ES as option available on target. 
LIBVERSION 
This string specifies the library’s version. It also is displayed on AS 100ES. AS 100ES performs 
a version check of the PC element library’s version (TED-file) and denies the download of the 
application in case of differences. 
BIND 
This string specifies the add-on options that shall be bound to this library; thus, several 
instances of this command are possible. 
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The Image Builder assumes that a pair of option files with a prefix that is specified as % BIND 
value and suffix “.ODF” and “.ABS” are available in current working directory. 


If, for instance, the value of % BIND is “POWER”, the Image Builder assumes following files in 
the current working directory: 


° POWER.ODF (option definition file) 
° POWER.ABS (linker output of object code) 


The %BIND commands must be the last commands in file. 


COMMENT 


This entry gives the possibility to add comments to the file. 


Example 


The following Figure 4-4 shows the structure of an Image Builder command file: 


% TARGET: “AC 110” 
%LIBNAME: “POWER” 
%LIBVERSION: 1.0/2 
%BIND: POWER 


%COMMENT: Example of Image Builder Command File 


Figure 4-4. Image Builder Command File (Example) 


4.2.3 Loading Procedure 
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Libraries are appended to the system software residing in the Processor Module. 


Therefor, after invoking the Image Loader “LOADER32.EXE”, the system software is copied 
into the RAM of the Processor Module. The loading software then sends performs following 
steps: 


1. Reboot the target into option loading procedure. 


2. Send library header information to the target: 
The target checks the absolute length of the add-on option and, if it fits to RAM as well as 
to FPROM later on, copies it to RAM at the end of system software. 


3. Send image data for each option. 


4. Finish library loading: 
The target relocates all entries, e.g., the PC element entry code. 


5. Send “Save to FPROM” command: 
The entire system software in FPROM is exchanged by the system software in RAM. 


6. Reboot the target to activate the new system software. 


It is obvious, that, depending on the state of option loading, a restart of the PM or 
communication faults have different impact. 
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Once the system software has been erased, an initialization of the PM automatically makes a 
reload of the entire system software necessary. As long as the FPROM has not been cleared, a 


reboot just requires a new option installation. 
4.3 Building Option Files 


4.3.1 Structure 


Options contain the executable code that is called by the function block (FB) interpreter if it is a 
PC element option. The FB interpreter is part of the system software. 


The physical structure of an option is illustrated by following figure: 


Option 1 Header 


Offset to next option 


Additional Information 


Code 


Interface Library 
Option 2 


Figure 4-5. Physical Structure of Options 


4.3.2 Option Definition File Syntax 
Each add-on option, e.g. a PC element, is to be defined by one option definition file (ODF-file). 
As in the BLD-file, all entries must start with the “%” sign and end with “:”. 
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The syntax of this file type is: 


Table 4-2. Option Definition File Syntax 


Item Data Format Format 
NAME char [20] Name of the option, without blanks. 
VERSION char [13] Version of the option. 
TYPE char [12] Type of the option: 
PC-ELEMENT for PC elements 
TYPCODE Hexadecimal value | Type code of the PC element 
RAMSIZE Number of 16-byte | Amount of RAM needed additionally for 
pages the option. 
COMMENT char [] File comment, may be placed anywhere. 


Each line in file must be lead separately 
by this entry. 


NAME 


This is the name of the option. Although it is not reported to the PC element user, it’s definition 
is mandatory for documentation purposes. 


VERSION 


This is the version of the option. For documentation purposes, this entry must be set. 


TYPE 
This specifies the type of the option. Currently, the only valid entry is “PC-ELEMENT”, 


TYPCODE 


This is the type code the option shall use. Valid type codes are from 0x400 up to 0x500 
(exclusively) in 4 byte increments. The type code must be used for one option exclusively. 


RAMSIZE 


This entry specifies the size of RAM that is needed in addition to historical data (see Chapter 
4.3.6.4 "Historical Data" on page 4-31). The RAM specified in 16-byte pages is reserved 
during system’s start-up and taken from system RAM resources. 


COMMENT 


This entry gives the possibility to add comments to the file. 
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4.3.3 Object File 


4.3.4 Absolute File 
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Example 


The following Figure 4-6 shows the contents of the option definition file: 


%NAME: MODBMON 
%NVERSION: 1.0/0 

%TYPE: PC-ELEMENT 
%TYPCODE: 0x404 
%RAMSIZE: 0x20 


%COMMENT: Example of option definition file 


Figure 4-6. Contents of Option Definition File (Example) 


As an intermediated output of the compiler and input for the linker, the object code (usually an 
OBJ-file) serves. 


To allow loading at an random address, add-on options must be written position independent. 
That means for the assembler programmer that PC relative instructions must always be used. 
The C programmer shall set the compiler options accordingly. 


Using a Microtec C-Compiler, following switches should be used: 


Syntax: 
MCC68K <source file> -I<include file directory> -upd -Mcp -nOc -c -A 
The -upd, -Mcp, -nOc and -c options are mandatory, the others are recommendations. If 


optimization is required, the respective options may be set freely. 


NOTE 


Due to possible changes in the header files, all source files must be re-compiled 
for usage on new versions of Advant Controller 100 Series. 


The linker output absolute file also serves as input for the Image Builder. Following conditions 
are to be fulfilled: 


° its format has to be Motorola S-Records; 


° the special and normal function entry addresses (FUNCTIONOO / FUNCTIONO1) must 
be declared as “externals”’; 


° one ABS-file must only contain the object code of one option (binding several options is 
done by the Image Builder); 


° the start address and size must be quad-aligned; 


° the generated code must match the processor type (68000, 68340 or CPU32). 
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NOTE 


An option must not exceed the size of 64 kByte. Each option contains the 
Interface Library, from which mathematical or system functions are called. The 
distance for jumps to functions has this maximum value. 


Necessary Commands: 


To generate a Motorola S-record file using the Microtec Linker, the linker command file must 
contain the following lines: 


Table 4-3. Necessary Linker Commands 


Command Value Meaning 
CHIP CPU32 Generate code for processors of CPU32 type. 
LISTABS PUBLICS List publics in output (S3-) file: 
This enables the Image Builder to find the addresses 
for normal and special functions (FUNCTIONOO / 
FUNCTIONO1). 
ALIGNMOD_ | CODE=4 Align code at 4-byte (DWORD) boundaries: 
This is necessary to avoid address errors when the 
processor executes the code instructions. 
ALIGNMOD _ | DATA=4 Align data at 4-byte (DWORD) boundaries: 
This is necessary to avoid address errors when the 
processor accesses data. 
FORMAT $3 Generate absolute files of S3-Record format: 
This is a necessary input for the Image Builder. 
EXTERN FUNCTIONOO, | Define the normal and special function labels as 
FUNCTIONO1 | externals (needed for correct output in ABS file). 
LOAD <module> Links <module> to the output file (the object code of 


the PC elemeni(s)). It is possible to load more than 
one module. 


The call of the linker should look as follows: 


Syntax: 


LNK68K -c <command file name> -o <output file> -M 


NOTE 


It is mandatory to load the Interface Library (see also Chapter 4.3.9) with each 
option using the LOAD command. Due to possible changes in the library, all 
options must be re-linked for usage on new versions of Advant Controller 100 


Series. 
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4.3.5 PC Element Physical Structure 


Below options, the PC element option is a special case: the executable code is called by the 
function block (FB) interpreter. The FB interpreter is part of the system software. 


The physical structure of a PC element option is illustrated by following figure: 


Option 1 Header 


Offset to next option 


Type Code 


Additional Information 


Special Function Code 


Normal Function Code 


Option 2 


Figure 4-7. Physical Structure of Options 


Important values that define a PC element option are described in following chapters. 


4.3.6 PC Element C-Language Template 


Although it might be necessary for performance reasons to write PC elements in assembly code, 
for readability and clarity it is highly recommended to write them in C. 


An universal assembly language frame PCFRAME.ASM is provided for the PC elements which 
saves registers, sets up some needed variables and calls the C-code of the PC element. After its 
execution, the registers are restored and the next element is jumped to. This frame is contained 
in the Interface Library for the C programmer and in the file PC_SKELE.ASM for the 
assembler programmer, respectively. 


A PC element consists at least of two parts, the “Special Function” and the “Normal Function”. 
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Special Function 


This is used to initialize internal variables. It is only executed once, when the PC Element is 
called the first time. For instance, it should initialize the local data area. 


A typical usage is the initialization of outputs and the local data area. 


Add-On option developers must name it PCspecial. 


Normal Function 
This is the routine which actually does the work of the PC element. 


Specify here the normal behavior of the PC Element, for instance the add operation of an adder 
PC element. 


Add-On option developers must name it PCnormal. 


The structure ObjectCode defines how the object code for the PC element looks like. Its 
structure is described later in this chapter. 


The structure LocalData defines how the local data for the PC element looks like. 


Please note, that both pointers objCodeP and localDataP, respectively, may not be changed 
during execution of the PC element. 


Two parameters *objCodeP and *localDataP, respectively, are given to both routines. 


objCodeP points to the object code of the PC element. It is used to access the offsets to the 
input/output areas, to the optional call and function parameters and to the also optional local 
data area offset. 


localDataP points to the PC program’s local data area which contains the input/output data and 
-optionally-storage for values which must be retained until the next activation of the PC 
program. Its actual size, which may depend on the parameters specified by the user, is planned 
by AS 100 Series ES during target code generation. 


The input values of the PC element are placed in the local data area before the execution of any 
PC elements of the application program. Similarly, the output values are stored in the local data 
area, too. After execution of all PC elements in an application program, they will be transferred 
to I/O modules or other PC programs via the common data area. 


The local data area is used for permanent storage of data; this means, the data will be available 
again at the next call of that PC element. Several PC elements of the same type will each have 
their own local data area. 


The memory layout of the local data area is defined with the structure LocalData in the 
template. 


Access to the local data area is done using the offsets to the respective items which are located 
in the object code. Those offsets are added to */ocalDataP; the resulting pointer is used to 
access the value itself. 


Please note that the offsets are specified as BYTE distances from *localDataP: casting may by 
necessary to obtain the correct data pointer with an add operation. 
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A template of a C Language PC element is shown in Figure 4-8. 


#include "STANDARD.H" 
#include "OSC_IL.H" 
/* 
is 
typedef struct { 
<type> <name>; /* define the elements of the local data area here */ 
<type> <name>; 


definition of the PC element's object code 


} LocalData; 


typedef struct { 
WORD Typcode; /* Type code for the PC element */ 


WORD Size; /* size of the object code structure (bytes) */ 
WORD Cp; /* Call parameter(s) */ 
WORD Fp; /* Function parameter(s) */ 


/* ... further entries ... */ 
WORD histdatOffs; /* local data area (optional) */ 
/* this is relative to to localDataP */ 
WORD inputOffs; /* PC element input(s) */ 
WORD outputOffs; /* PC element output(s) */ 
/* ... further entries ... */ 
} ObjectCode; 
/* 
[RERERER EES ERERESESERER EES PC Elements SPECIAL routine KRKKKKKKKK KEKE EKER RRR EERE KREE 
*/ 
void PCspecial (const ObjectCode *objCodeP, WORD * const localDataP) { 
/* ...optional special mode code goes here...*/ 


} 


/* 
KRKKKKEKKKKKKKEKKKEKKKKKKKKKEKK PC Elements NORMAL routine KKRKKKKEKKEKKKEKKEKEKKEKKRKEKKKRKEKEKKKKKKKER 
af 
void PCnormal (const ObjectCode *“objCodeP, WORD * const localDataP) { 
/* ...normal mode code goes here... */ 


} 


Figure 4-8. C Language PC Element Template 


4.3.6.1 Special Function 
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Each PC element option must be supplied with a special function, even if no actions are taken 
there. 


The special function is executed by the FB interpreter in following cases: 


° once during a new download of the application, 
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° cyclically as long as the RESET input if the superordinate CONTRM is set to “1”. 


Due to that, the special function is ideal to initialize output values and historical data. This is 
necessary especially for boolean output values: if they are not initialized to “PCTRUE” or 
“PCFALSE”, the AS 100ES will display an “x” in on-line mode at corresponding terminal. 


The special function prototype is fixed defined as: 


void PCspecial (const MyObjectCode *objCodeP, const BYTE 
*localDataP) 


where 


ob jCodeP is the pointer to PC element’s object code (see below) and localDataP is the 
pointer to the local data area for the PC element. 


Both pointers are set up by the FB interpreter for each PC element; for a description see Chapter 
4.3.6.3 and 4.3.6.5. 


CAUTION 


Both pointers must not be changed; the FB interpreter increments them before 
passing them to the next element. 


4.3.6.2 Normal Function 
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This is the object code that is executed, most often cyclically, by the FB interpreter if the 
superordinate CONTRM is running. 


Normally, it’s function consists of three parts: 
1. reading input values, 

2. processing input values (calculating), 

3. writing output values. 


The normal function is very time critical: if the application programmer specifies a short cycle 
time at CONTRM, a very short time remains for execution of this code. 


If the execution takes too long, the CONTRM-task will not get ready in it’s specified cycle time; 
this will result in processor overload respectively 3rd- or 4th-activation of this task and the 
possible danger of application shut down. 


NOTE 


Historical data can be used to reduce system load during normal execution: if 
inputs are not changing, output results - previously stored as historical data - may 
be written directly to output pins without calculating them again. 

Also seldom changing values and constants should be stored in historical data 
area for fast access. 


The normal function prototype is fixed defined as: 
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void PCnormal (const MyObjectCode *objCodeP, const BYTE 
*localDataP) 


where 


ob jCodeP is the pointer to PC element’s object code (see below) and LlocalDataP is the 
pointer to the local data area for the PC element. 


Both pointers are set up by the FB interpreter for each PC element; for a description see Chapter 
4.3.6.3 and 4.3.6.5. 


CAUTION 


Both pointers must not be changed; the FB interpreter increments them before 
passing them to the next element. 


4.3.6.3 Object Code Structure 


The object code structure is generated by AS 100ES according to the definition in PC element’s 
PED-file and forwarded to the PC element code by means of the pointer ob j}CodeP. 


The physical structure looks as follows: 


Type Code 


Size (in bytes) 


Call Parameters 
(if present) 


Function Parameters 
(if present) 


Offset to Historical Data 
(if present) 


Offset(s) to Input Values 


Offset(s) to Output Values 


~<q—_§_ 16 bit > 
Figure 4-9. Physical Structure of Object Code 


Only Type Code and Size are mandatory, all other fields are optional. However, their sequence is 
important and may not be altered. 
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The object code structure delivers values given by the application and offsets to in- or outputs in 
local data area, all aligned to WORD (16-bit) boundaries. 


Call parameters and Function parameters are always BYTE values. Because of M68000’s 
addressing mechanism, it is not allowed to have an odd number here. Hence, if a PC element 
requires an odd number of these parameters, they must be filled to an even number using a 
dummy byte. 


When the PC element has to maintain ’static’ values (as opposed to temporary values which are 
valid only during runtime of the PC element), the offset to historical values will point into the 
local data area for that PC element. 


Accessing I/O is done via the offsets to terminals. Those point to those locations in the local 
data area which are copied to and from by Advant Controller’s I/O software. 


In the C-language, the structure is to be defined as follows: 


#include "STANDARD.H" 


typedef struct 
{ 

WORD typeCode;/* Type code for the PC element */ 
WORD size;/* Size of the object code structure (bytes) */ 
BYTE cpl; /* Call parameter(s), if present*/ 
/* ... further cp entries or dummy ... */ 


AUOO 


ia) 


BYTE fpl; /* Function parameter(s), if present */ 
/* ... further fp entries or dummy ... */ 


WORD histdatOffs;/* Historical data area (optional) */ 
WORD inputOffs;/* PC element input(s) */ 

WORD outputOffs;/* PC element output(s) */ 

/* ... further entries ... according to .PED-file */ 


} MyObjectCode; 
Figure 4-10. C-Language Structure of Object Code 
The real content of the object code structure depends on the definition in the corresponding 
PED-file—AS 100ES generates data structure and offsets accordingly. 
Thereby, t ypeCode and size are mandatory - all other entries are user defined. 
Except for typeCode, size, fp and cp, all values are 16-bit offsets into the local data area 


of the PC element, regardless the data type specified in PED-file. 


CAUTION 


Since call (cp) and function (fp) parameter values have byte size, the developer 
MUST align them to even sizes. That means, that if only one call parameter is 
used, another one—a dummy—must be inserted into the structure. The same 
applies to function parameters. 
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TypeCode 


The most important figure for an option is the type code that also is used for built-in PC 
elements. 


The type code specifies the place within a FB jump table, which serves as an input for the FB 
interpreter. At the concerned entry, the interpreter finds the code start addresses for normal and 
special functions (see chapters below). Since code addresses have a 4-byte size, only type codes 
are allowed, which can be divided by 4 (0x400, 0x404, etc.). 


Therefor, it is extremely important to use type codes, which are not occupied by basic PC 
elements. For add-on options, generally the range between 0x400 and Ox4FC is reserved. 


The type code, chosen for the PC element, must also be inserted into the PED-file. 


Size 


AS 100ES calculates the size of the object code and inserts it at that location. Normally, it is 
used only by the FB interpreter. 


Call Parameters 
Call parameters are variables for PC elements, defined during their creation. 


They often determine the layout of the PC element: the number of it’s input and output values. 
The PC element functions must check those values during in- or output initialization to avoid 
accesses into data areas not related to this PC element. 


Call parameters cannot be changed on-line. 


Function Parameters 


Function parameters are inputs that cannot be connected to outputs of other elements or 
PCPGM I/O. This means, that the developer has to check for changes of those values only in the 
special function of the PC element. 


Offset to Historical Data 


This is the offset to the historical data of the PC element. See Chapter 4.3.6.4 below. 


Offsets to In- and Outputs 


Each input and output has it’s own offset into the local data area. Normally, inputs and outputs 
are grouped and located sequentially behind each other, but this cannot be guaranteed. 


4.3.6.4 Historical Data 


Defining historical data in the PED-file (entry NOBYTESHISTORIC), allows storage of 
information besides in- and output values. 


Normally, it is used store “static” data, e.g. seldom changed values or constants into it. This may 
reduce computing time by calculating them once. 
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The size of historical data affects the memory consumption of the PM if the application is 
loaded; each PC element has it’s own area. Thus, the structure of it is to be defined by the PC 
element developer. 


The run-time system handles historical data areas in following cases: 
° it initializes the data area during a new application download; 
° it copies the data area during on-line changes, so values are kept. 


The calculation of the pointer to historical data is: 


BYTE *histDatP = (BYTE *) (localDataP + ob jCodeP->histDatOffs) ; 


If no historical data is used, NOBYTESHISTORIC must be set to 0 in the PED-file. 


4.3.6.5 Local Data Structure 


As historical data, each PC element has it’s own local data structure, even if they are of the same 
type. The pointer to it is passed to normal and special function as localDatabP. 


As historical data, the local data is initialized during download of a new application and copied 
during on-line changes of the superordinated CONTRM. This means that the same data is 
available for each PC element execution as long as there are no other elements that are 
connected to the inputs. 


The input values of the PC element are placed in the local data area before any PC element of 
the application program is executed. Similarly, the output values are stored in the local data 
area, too. After execution of all PC elements in an application program, they will be transferred 
to I/O modules or other PC programs via a common data area. 


The local data area is used for permanent storage of data; this means, the data will be available 
again at the next call of that PC element. 


It’s actual size and structure layout, is planned by AS 100ES during target code generation using 
the information given in corresponding PED-file. It is necessary to define exactly the same data 
structure as MyObjectCode to read and write from or to the correct locations. 


Access to the local data area is done using the offsets to the respective items which are located 
in the object code. Those offsets are BYTE distances from 1ocalDataP and must be added to 
localDataP; the resulting pointer is used to access the value itself. An example for accessing 
the data is the following: 


WORD myValue; 
myValue = *(WORD *) (localDataP + objectCodeP->inputOffs) ; 


4.3.7 C-Language Coding 
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To allow an easy use of C modules, an universal assembly language frame is included in 
Interface Library. As an example, the extension diskette contains PCFRAME.ASM. 


This frame saves registers, sets up some needed variables and calls the C-code of the PC 
element. After its execution, the registers are restored and the jump to the next element is 
performed. 
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During design and coding, following rules should be observed: 


° The code has to be position independent: far jumps into other modules cannot be 
performed without loosing the independency. 


° Use historical data instead of static variables for these reasons: 


— the PC element (respectively it’s code) may be instantiated several times and called in 
non-deterministic order; 


— static data is not computed by AS 100ES when calculating the memory requirements 
for an application; 


— far static data may corrupt position independency. 


° Use system functions from Interface Library wisely—most of them consume much 
computing time that may lead to overload of fast application tasks. 


4.3.8 Assembly Coding 
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Although assembly coding is not recommended, some information about register usage and FB 
interpretation shall be given here. 


Processor Register Usage 


At start of the PC element, register AO points to the type code of the PC element itself. It may be 
altered at runtime of the PC element. 


A1 serves as a pointer to the beginning of the PC element's internal data area; to use the internal 
data area, the offsets to the historical values area and to the I/O terminals, respectively, must be 
added to Al. However, the register itself may not be changed at runtime of the PC element, that 
means it must be restored to its original value after execution. 


The register usage for PC elements is defined as below. Except of AO, none of the listed 
registers may be modified; that means they must be saved before use. 


Table 4-4. Assembly Register Usage 


Register Usage 
AO Pointer to object code 
Al Base pointer to local data area 
A2 Base pointer to function block table, the jump tables 
NORTA and SPETA 
A5 Reserved for internal use 
A7 Stack pointer 
D7 Execution mode (normal, special) 
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Passing the control to the successor function block 


When a PC element is terminated, the next one must be called. To do so, pass the control to the 
next function block with the JNFB macro. 


Use this macro like a RTS instruction for either the normal routine, or the special routine. 


4.3.9 The Interface Library 


Since each add-on option uses standard C-functions (mathematical, string, etc.) and sometimes 
the need for usage of system function arises, the System Software Extensions diskette also 
contains an Interface Library. 


The Interface Library contains stubs of function calls which may be called by an option. Those 
functions reside in the Processor Module’s FPROM memory and have neither fixed addresses 
nor publicly defined names which would allow linking. The are therefore called via TRAP calls. 
Those TRAP calls are issued from the stubs in the Interface Library. The Interface Library file 
(AC70IL.LIB, AC110IL.LIB, or AC160IL.LIB) which contains the Interface Library's routines 
must be included in every linker command file. 


Following rules must be fulfilled using Interface Libraries: 
° Each option (linker command) has to include the library once. 


° The function call must exactly match the prototype given in library header file (AC70OIL.H, 
AC110IL.H, or AC160IL.H). 


° The Interface Library must be linked to the option by means of insertion into the linker 
command file. 


CAUTION 


Due to possible changes in function prototypes and library contents, all PC 
element sources (C- and ASM-files) must be re-compiled and linked for new 
versions of a system software. 


The global table MainTable contains a pointer to the first unused flash PROM location. The 
Option Installer first writes a library control block to this location, containing a pointer to the 
end of the new code, and data identifying the library. After that, the options themselves 
including their add-on control blocks are written. 


4.3.10 Compiling and Linking 
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To allow loading at an random address, add-on options must be written position independent. 
That means for the assembler programmer that PC relative instructions must always be used. 
The C programmer shall set the compiler options accordingly (see below). 


The C compiler must be called with the following switches: 
MCC68K <source file> -I<include file directory> -upd -Mcp -nOc -c -A 


The -upd, -Mcp, -nOc and -c options are mandatory, the others are recommendations. If 
optimization is required, the respective options may be set freely. 
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To generate a Motorola S-record file usable for the Image Builder, with the public symbols and 
their addresses included, the linker command file must contain the following lines: 


CHIP 
LISTABS 
FORMAT 
BASE 
EXTERN 


LISTMAP 


68000 

PUBLICS 

S) 

0 
FUNCTIONOO,FUNCTIONO1 


publics, internals,crossref 


...more commands as needed 


LOAD 
LOAD 
LOAD 
LOAD 


LOAD 
END 


<your object module #1> 
<your object module #2> 


<your object module #n> 


AC100IL.LIB 
MCC68KPC.LIB 


Figure 4-11. Sample Linker Command File 


Please note that there may be only one PC element in each complete S-Record file. The binding 
of several of them is done by the Image Builder. 


The batch file LINK.BAT on the distribution diskette may be used for linking. 


Usage: 


LINK <file name> 


4.3.11 C Runtime Library 


The C standard routines are available to the option developer through the Interface Library 
(AC70IL.LIB, ACII0IL.LIB, or AC160IL.LIB), see Chapter Table 5-6. "System Call 
Summary" on page 5-43. 


For a detailed description of them, please refer to Ready Systems’ documentation. 


4.4 Files for AMPL Control Configuration 


4.4.1 PC Element Description Files 
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They are used to define the layout in AMPL Control Configuration and the object code 
structure. The syntax is described in AMPL Control Configuration PC Element Description for 
Advant Controller 100 Series, Designer’s Guide, an example given in Chapter A.3.1 "PC 
Element Description File" on page A-71. 
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CAUTION 


The type codes and object code structures defined in this file must exactly match 
those in corresponding option definition files. 


For targets supporting application backtranslate functionality, it is absolutely 
necessary that the file name prefix does not exceed a length of more than 7 
characters. Otherwise, the option will not be correctly supported. 


4.4.2 Target Element Description File 


Target Element Description (TED) file is used to define an entire element library consisting of 
one or more PC elements. The TED-file is to be specified for each target version. 


The syntax is described in the AMPL Control Configuration Setup Add-ons Designer's Guide, 
an example given in Chapter A.3.2 "Target Description File" on page A-74. 


NOTE 


For targets supporting application backtranslate functionality, it is absolutely 
necessary that the file name prefix does not exceed a length of more than 7 
characters. Otherwise, the option will not be correctly supported. 


4.5 Contents of an Distribution Disk 


A distribution disk shall contain the following files: 


LOADER32.EXE 
32-bit option loader working under Windows NT 4.0 


<option> IMG 
the image file to be loaded to Advant Controller 100 Series. 


<option>.BAT 
Batch file to automatically invoke the loader with the image file. 


<option>.TED 
Target description file for AMPL Control Configuration. 


<option>.PED 
Containing one or more PC element descriptions for AMPL Control Configuration. 


README.TXT 
Distribution information. 


The option can either be installed directly from the diskette or the files can be copied manually 
to the local hard disk. 


4.6 Loading the Option to the Controller 


Connect your AS 100ES (or standard PC) to the serial interface for Tools of the Processor 
Module. This is either labelled “CH1” or “Com A” depending on the type of Processor Module. 
You can use the same cable that is used to connect Function Chart Builder to the Processor 
Module. 
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Insert the option distribution diskette into the your PC and use Windows NT Explorer to browse 
to the diskette drive. Now load the option to the Processor Module by double-clicking the 
<option» .BAT file. The loader pops up and the loading process starts automatically. 


NOTE 


You may need to select the correct serial interface (COM1, COM2, ...) on your 
PC before loading. 


4.7 Adding the Option to AMPL Control Configuration 
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It is assumed that you have an Advant Station 100 Series Engineering Station or a standard PC 
with or a standard PC with AMPL Control Configuration 1.7 or higher installed, and AMPL PC 
and DB Libraries 1.3 or higher. 


Insert the option distribution diskette into drive A:, press the Start button and select Advant | 
Engineering | Utilities | Setup Add-ons 4.7-0. 


Choose “copy and compile” and check “replace destination files”, then click OK. Browse to the 
diskette drive and click Open. The option is now being installed for AMPL Control 
Configuration. 


Application Builder should offer under “available options” the new option(s). 


If you have an existing node, then the new option becomes available after selecting the node in 
Application Builder and pressing the modify... button. 
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Chapter 5 Programmer’s Reference 


5.1 Introduction 


This chapter describes the system calls which are available for developers who want to develop 
an add-on option for Advant Controller 100 Series. The name, the C prototype definition are 
listed as well as call parameters and possible restrictions. If necessary, an in-depth description of 
the procedure’s function is added. 


5.2 Data Types 


Data types which are used in conjunction with system calls. 


5.2.1 Simple Data Types 
Table 5-1 lists the simple data types 


Table 5-1. Simple Data Types 


Name Description Value Range 
char 8 bit signed -128 to 127 
BYTE 8 bit unsigned 0 to 255 
short 16 bit signed -32,768 to 32,767 
WORD 16 bit unsigned 0 to 65,535 
int 32 bit signed -2,147,483,648 to 2,147,483,647 
long 32 bit signed -2,147,483,648 to 2,147,483,647 
DWORD 32 bit unsigned 0 to 4,294,967,295 
float 32 bit signed According to IEEE. 
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5.2.2 Compound Data Types 


Table 5-2 lists the compound data types 


Table 5-2. Compound Data Types 


Name Description 


struct ObNa Defines the name of a memory object as 
{ itis used by the memory management. 
char type; 
char scope; 
WORD version; 
}; 

union ObjectNameUnion Union for easier access to memory 
{ objects. 


DWORD ObjectName; 


struct ObNaSplitName; 
}; 

struct date_struc Date representation. 
{ 


short year; 


short month; 
short day; 
}; 

struct time_struc Time representation. 
{ 


short hour; 


short minute; 
short second; 
short fraction; 


hi 
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5.2.3 Special Data Types 


Following table lists data type that have a special meaning in AC 160: 


Table 5-3. Special Data Types 


Type Size Value Range 


MASTER BOOLEAN | 16 bit unsigned Used as boolean values at PC element terminals: 
Ox00FF (PCFALSE 
OxFFOO (PCTRUE) 


ma 


MASTER date 32 bit unsigned Date representation: days since 01.01.1980. 


MASTER time 32 bit unsigned Time representation: 100 micro second units elapsed 
since start of the day: 0 to 8639999 


5.3 Standard System Definitions 


PC elements use a special representation for binary values to facilitate error checking: 


OO000000 | 11111111 = FALSE 


11111111 |OQOOO0000; =TRUE 
«—_—____— 16 bit —_____4 


Figure 5-1. Binary Value Format 


The following table lists all standard definitions for Advant Controller 100 Series: 


Table 5-4. Standard System Definitions 


Name Value Data Type Meaning 
RET_OK 0x0000 WORD Return value from system functions. Indicates 
successful execution. 
TRUE 0x0001 BOOLEAN = 
FALSE 0x0000 BOOLEAN = 
PCTRUE OxFFOO WORD Value “1” at boolean terminals of PC elements 


PCFALSE OxOOFF WORD Value “O” at boolean terminals of PC elements 
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The contents of the 16 bit are OxFFOO for TRUE and OxOOFF for FALSE. Any other value is 
considered invalid. Symbols are provided for use by the programmer; they are named PCTRUE 


and PCFALSE, respectively. 


Floating point data is according to the IEEE representation. 


5.4 Standard C-Functions 


The following C standard routines are available to the option developer through the Interface 
Library ACxxxIL.LIB (xxx = type of controller: 70, 110, 160). 


For a detailed description of them, please refer to Ready Systems’ documentation. 


Table 5-5. Standard C-Functions 


Group 


Functions 


Arithmetic functions abs, 


exp, 


acos, 
atoi, 
fabs, 
hypot, 
log10, max, min, modf, pow, 
sinh, 


atan2, atof, 
ceil, cos, cosh, 
frexp, frexpl0, 
ldexp, ldexp10, log, 
sign, 
tanh 


asin, 
cabs, 

floor, 

labs, 


atan, 
atol, 


sin, 


sqrt, square, tan, 


String functions 


strcat, 
strchr, 
strncmp, 
strcspn, 
upper 


strncat, 

strrchr, 
index, 
strlen, 


strcpy, strncpy, 
strpbrk, strcmp, 
rindex, strspn, 

lower, reverse, 


Character classification functions 


isalnum, 
iscntrl, 
isodigit, 
isupper, 


isblank, 
islower, 
isspace, 


isascii, 
isgraph, 
ispunct, 


isalpha, 

isdigit, 
isprint, 

isxdigit 


Character conversion functions 


toascii, 


toint, tolower, toupper 


Byte string manipulation functions 
swab 


bemp, 


bcopy, bfill, brev, bzero, ffs, 


5.5 System Software Functions 


5.5.1 Overview 


This chapter describes the system software function calls, which are offered by the Interface 
Library ACxxxIL.LIB (xxx = controller type). For the usage of any function, the statement 


#include “ACxxxIL.H” 


must be inserted into C-source modules. 
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Table 5-6 lists all system calls grouped according to their function. 


Table 5-6. System Call Summary 


Name Description 
Option Handling 
Membase Delivers the option’s memory base. 
StartReason Delivers the reason why the install routine was called. 


OptionInstalled | Checks wether a Build-In option is activated. 


Memory Management 

OS_obj_base Get the address of a memory object. 
OS_obj_rdy Set memory object to status complete. 
OS_obj_size Returns the size of a memory object. 


OS_obj_status Get the status of a memory object. 


OS_obj_termin | Terminates the access to a domain and decrements its “in-use” counter. 


GetlOAddress Fetch the communication memory address of the specified signal from COIA. 


TracTrap") gets redundancy partner information. 
Hardware Access 
HW_SetLed Switches an LED on the front panel of a Processor Module on or off. 


HW_SetRelay Pick-up or release the built-in relay. 


HW_SetOSP Handles the “Output to Safe Position” signal towards the I/O modules. 


HW_rdmodsw Read the position of the start mode switch. 


HW_rdtimdat Read time and date from real time clock. 

HW_display Shows a “string” on the display of the Processor Module (consisting of two 7- 
segment display units). 

ReadLong Read a value from an I/O module. 

WriteLong Write a value to an I/O module. 

Miscellaneous 

gtime_fine Get the system tick count. 

getCycletime Get the cycle time of the current task in units of 100 us. 

fci4dat Convert date from internal to external representation. 

fci4tim Convert time from internal to external representation. 


(1) Advant Controller 160 only. 
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5.5.2 Membase 
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Abstract 


Delivers the option’s memory base. 


Prototype 


void *Membase(void); 


Input 


None. 


Output 


Pointer to the reserved memory. 


Modified Variables 


None. 


Description 


Restrictions 


None. 
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Abstract 


Delivers the reason why the install routine was called. 


Prototype 


int StartReason(void); 


Input 


None. 


Output 
The reason for the start: 
COLD_START Power up or reset, switch in position CLEAR 
WARM_START Power up or reset, switch in position AUTO 
NOT_AVAILABLE System is running normally 


Modified Variables 


None. 


Description 


This call delivers the start reason for the initialization routine. 


Restrictions 


None. 
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5.5.4 Optioninstalled 


Abstract 


Checks wether a Build-In option is activated. 


Prototype 


int OptionInstalled(short oid); 


Input 


oid The option’s ID number. 


Output 
TRUE Option installed 
FALSE Option not installed 


Modified Variables 


None. 


Description 


Restrictions 
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5.5.5 OS obj base 


Abstract 


Get the address of a memory object. 


Prototype 


void *OS_obj_base(union ObjectNameUnion objnam); 


Input 


objnam Name of object. 


Output 


The function returns the object’s base address or NULL if it does not exist. 


Modified Variables 


None. 


Description 


Besides delivering the base address of a memory object, this call locks that object for the 
use of the calling task only. That means no other task may legally access the object while it 
is locked. After accessing the object, it must be released for the use of other tasks by 
calling OS_obj_termin. 


Restrictions 


Failing to release a domain with OS_obj_termin will result in erratic system behavior. 
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5.5.6 OS obj_rdy 


Abstract 


Set memory object to status complete. 


Prototype 


void *OS_obj_rdy(union ObjectNameUnion objnam, int *status); 


Input 


objnam Name of object. 


Output 
status Status 
RET_OK Object exists and was incomplete 
PBJ_COMPLETE Object exists and is complete 
OBJ_NOTEXISTS Object does not exist 
OBJ_ILLNAME Object name not allowed 


Modified Variables 


None. 


Description 


Set an object of the memory management to status “complete”. 


Restrictions 


None. 
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Abstract 


Returns the size of a memory object. 


Prototype 
WORD OS_obj_size(DWORD name); 


Input 


name Name of object. 


Output 


The function returns the size in bytes of the object or NULL if it does not exist. 


Modified Variables 


None. 


Description 


Restrictions 


None. 
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5.5.8 OS obj status 


Abstract 


Get the status of a memory object. 


Prototype 


WORD OS_obj_status(union ObjectNameUnion name, int *status); 


Input 


name Name of object. 


Output 
The function returns the object’s version if it exists: 
— “active” or “alternative” if explicit version is requested 
— explicit version if “active” or “alternative” version is requested 
- NULL if object does not exist. 
Status contains the following return code: 


OBJ_UNDELETABLE Object is in use 


OBJ_COMPLETE Object exists and is complete 
OBL_INCOMPL Object exists but incomplete 
OBJ_NOTEXISTS Object does not exist 
OBJ_ILLNAME Object name not allowed 


Modified Variables 


None. 


Description 


If the memory object with the given name exists and is complete, its version is returned. 


Restrictions 


None. 
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5.5.9 OS obj_termin 


Abstract 


Terminates the access to a domain and decrements its “in-use” counter. 


Prototype 


void OS_obj_termin(union ObjectNameUnion id); 


Input 


id Object identification. 


Output 


None. 


Modified Variables 


None. 


Description 


Restrictions 


None. 
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5.5.10 GetlOAddress 


Abstract 


Fetch the communication memory address of the specified signal from COIA 


Prototype 
DWORD GetIOAddress (Module_SixStruct adSIX, 
BYTE objectType, 
WORD addressBlockOrdinalNo, 
WORD addressNo); 
Input 
stationAndPosition, 
object type, 
addressBlockOrdinalNo = real or pseudo instance number 
addressNo = ordinal number within the addressBlock, 
Output 


ioAddress, if (jo Address == InvalidAddress) then an error occurred 


Modified Variables 


None. 


Description 


Restrictions 


None. 
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5.5.11 TracTrap 


Abstract 


For ABB internal use only. 
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5.5.12 HW_SetLed 


Abstract 


Switches a LED on the front panel of a Processor Module on or off. 


Prototype 
void HW_SetLed(int led, int state); 


Input 
led Denotes the LED to be switched on/off: 
—  Fled = Fault-LED 
— RunLed = Run-LED 
—  BatteryLed = Battery-LED 
state On or Off. 


Output 


None. 


Modified Variables 


None. 


Description 


Restrictions 


None. 
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5.5.13 HW_SetRelay 


Abstract 


Pick-up or release the built-in relay. 


Prototype 
void HW_SetRelay(int state); 


Input 
state On or Off. 


Output 


None. 


Modified Variables 


None. 


Description 


Restrictions 


None. 
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5.5.14 HW_SetOSP 


Abstract 


Handles the “Output to Safe Position” signal towards the I/O modules. 


Prototype 
void HW_SetOSP(int state); 


Input 
state On or Off. 


Output 


None. 


Modified Variables 


None. 


Description 


Setting the OSP signal to “On” causes all I/O modules in all connected racks to switch 
their outputs to “safe position”. This is usually—but not necessarily—0O for both digital 
and analog outputs. 


Restrictions 


None. 
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5.5.15 HW_rdmodsw 


Abstract 


Read the position of the start mode switch. 


Prototype 
BYTE HW_rdmodsw(void); 


Input 
None. 
Output 
The function returns the position of the start mode switch encoded as follows: 
STOP = 1 
COLD = 2 
WARM = 3 
UNDEF = -1 


Modified Variables 


None. 


Description 


Restrictions 


None. 
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5.5.16 HW_rdtimdat 


Abstract 


Read time and date from real time clock. 


Prototype 
long HW_rdtimdat(long *Idate); 


Input 


*Idate Address where to store the current date. 


Output 
Time in internal representation 


Date in internal representation. 


Modified Variables 


None. 


Description 


Restrictions 


None. 
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5.5.17 HW_display 


Abstract 
Shows a “string” on the display of the Processor Module (consisting of two 7-segment 


display units). 


Prototype 
void HW_display(char *string); 


Input 


string A two-character string. 


Output 


None. 


Modified Variables 


None. 


Description 
The following characters may be displayed: 
+,-,0...9, A...Z. 


Restrictions 


Due to the limited display capabilities of the 7-segment display, some of the characters 
cannot be displayed correctly. 
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5.5.18 ReadLong 
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Abstract 


Read a value from an I/O module. 


Prototype 
DWORD ReadLong(DWORD addr, WORD *status); 


Input 
addr Address to read the value from 
status Address where the status information for that call is stored: 


FALSE = _ No error occurred 
TRUE The value could not be read. 


Output 
The 32-bit value taken from the I/O module. 


Modified Variables 


None. 


Description 


This call handles a read access to the BIOB (the back plane I/O bus). Bus errors during the 
access are handled properly and the status information is set accordingly. Bus errors may 
occur because either the module is not inserted (spare), or not configured correctly. 


Restrictions 


None. 
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5.5.19 WriteLong 


Abstract 


Write a value to an I/O module. 


Prototype 
void WriteLong(DWORD addr, DWORD data, WORD *status); 


Input 
addr Address to read the value from 
data The value to be written 
status Address where the status information for that call is stored: 


FALSE = _ No error occurred 
TRUE The value could not be read. 


Output 


None. 


Modified Variables 


None. 


Description 


This call handles a write access to the BIOB (the back plane I/O bus). The status reflects 
the state of the previous BIOB access. Bus errors occur because either the module is not 
inserted (spare), or not configured correctly. 


Restrictions 


None. 
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5.5.20 gtime_fine 


Abstract 


Get the system tick count. 


Prototype 
DWORD gtime_fine(void); 


Input 


None. 


Output 


The 32-bit current system tick value. 


Modified Variables 


None. 


Description 


The delivered count represents the system tick with a resolution of 100 us. 


Restrictions 


None. 
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5.5.21 getCycletime 


Abstract 


Get the cycle time of the current task in units of 100 ps. 


Prototype 
DWORD getCycletime(void); 


Input 


None. 


Output 


The cycle time of the current task as 32-bit value. 


Modified Variables 


None. 


Description 


Restrictions 


None. 
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5.5.22 fci4dat 
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Abstract 


Convert date from internal to external representation. 


Prototype 


void fci4dat(long date, short extDate[3], *status); 


Input 
date 


extDate 


Output 
extDate 
status 
FALSE 
TRUE 


Date in internal format to be converted 


Address where to put the date converted to external format. 


List of three 16-bit values: year / month / day. 
Status of conversion: 
Successful 


Input out of range. 


Modified Variables 


None. 


Description 


Restrictions 


None. 
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5.5.23 fci4tim 


Abstract 


Convert time from internal to external representation. 


Prototype 


void fci4tim(long time, short extTimee[4], *status); 


Input 
time Time in internal format to be converted 


extTime Address where to put the time converted to external format. 


Output 
extTime List of four 16-bit values: hour / minute / second / fraction. 
status Status of conversion: 
FALSE — Successful 
TRUE Input out of range. 


Modified Variables 


None. 


Description 


The fraction is given in units of 100 us. 


Restrictions 


None. 
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5.6 Error Codes 


5.6.1 Image Builder 
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Following error and warning messages may appear during execution of the Image Builder: 


Code address of ’<identifier>’ is not 4-byte aligned (got: <address>h). 


Error: The address of external reference <identifier> (“FUNCT IONOO” or “FUNCTIONO1”), 
found in absolute file, is not quad-aligned. The address read was <address>. Alignment to 4- 
byte boundaries is adjusted in linker command file. 


Code in Absfile exceeds option limit (> 65535). 


Error: One of the option’s code is larger than 64 KB. If possible, split up functionality to several 
options. 


Code in Absfile is not ascending (erroneous address: <address> h). 


Error: When parsing the ABS file, the Image Builder found code addresses which are not 
contiguous or ascending. Ensure that the code is ascending and contiguous by correcting the 
linker command file. 


Command file does not contain a library name (%LIBNAME:). 


Error: The Image Builder could not find the “S LI BNAME” command in command file. It must 
be inserted. 


Command file does not contain a library version (%LIBVERSION:). 


Error: The Image Builder could not find the “s LIBVERS ION” command in command file. It 
must be inserted. 


Command file does not contain a target name (%TARGET:). 


Error: The Image Builder could not find the “s TARGET” command in command file. It must 
be inserted. 


Command file has wrong format. 


Error: The Image Builder command file has a wrong format. Most likely, the command 
“SBIND” appears before definitions for the library (LIBNAME, etc.). Change the order 
accordingly. 


Could not find ’<fileName>’. 


Error: One of the files required for sBIND command (ODF or ABS) is not present in current 
working directory. 
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Could not find code start in ABS-FILE! 


Error: The Image Builder was not able to identify the code start in absolute (.ABS) file. The 
code start is searched using addresses of external references “FUNCTIONOO” and 
“FUNCTIONO1”. Check you linker command file for the “EXTERNAL” command. 


Could not open ’<filename>’. 


Error: The file <filename> could not be opened for reading or writing. Make sure that no image 
files exists which are write-protected. 


Entry '<command entry>' ignored for '<file>'. 


Warning: An invalid entry <command entry> was found in definition file <file>. It has been 
ignored. 


Error while reading Absfile <filename>. 


Error: An unexpected read error occurred when parsing the absolute file <filename>. Ensure 
correct format of this file. 


Error while writing Image file. 


Error: It was not possible to write data to the image file. Make sure that there is enough space on 
your hard disk and a possibly already existing image file is not write-protected. 


No files specified in '<BLDfilename>', '<IMGfilename>' not generated. 


Error: The Image Builder did not find any valid BIND command in <BLDfilename> and 
could not bind any options. <[MGfilename> was not generated. 


No or wrong file name '<filename>' specified. 


Error: The filename <filename> specified with BIND command in Image Builder command 
file is not valid. 


No valid address(es) in ABS-File. 


Error: The Image Builder could not find valid PC element code addresses in absolute file. The 
code start is searched using addresses of external references “FUNCTIONOO” and 
“FUNCTIONO1”. Check you linker command file for the “EXTERNAL” command. 


No valid value for ’<command entry>’. 


Error: The value given for command <command entry> is not valid. 
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String for <command eniry> too long, truncated. 


Warning: A string entry for item <command entry> in Image Builder command or option 
definition file was found that exceeded the maximum number of characters. The string was 
truncated and possibly information is lost. 


TYPCODE must be dividable by 4. 
Error: The PC elements’ type codes must be dividable by 4. Valid values are 0x400, 0x404, etc. 


Unknown header entry specified in ODF-FILE! 


Warning: An unknown entry was found in option definition file. The entry was ignored. 


Unresolved header entry ’<command entry>’. 


Error: The necessary <command entry> line was not found in definition file. 


Value for TYPCODE is out of range (400h >= TYPCODE < 500h). 


Error: The value specified for sTYPCODE entry in option definition file must match the range 
between 0x400 and 0x500 (exclusively). 


5.6.2 Image Loader 


Following error and warning messages may appear during execution of the Image Loader: 


Could not find input file. 


Error: The add-on option image file specified at command line, could not be found. 


Could not read header from image file. 


Error: There was an error during read of the add-on option image file. Make sure that the image 
file has a valid content. 


Error during transmission of option header! 


Error: There was an unexpected error during creation of one of the options. Check the settings 
of the option that currently was to be loaded. 


Error reading option code from image file. 


Error: An unexpected error occurred during load of the option’s code. Make sure that the image 
file is not corrupt and check the image building process for this option 
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Error reading option header from image file! 


Error: An unexpected error occurred when the Image Loader tried to read the header 
information for the option currently to be loaded. Make sure that the image file is not corrupt 
and check the image building process for this option. 


File is not a loadable add-on image. 


Error: The image file specified in command line seems not to have the correct format or is no 
add-on image file. 


Function block number <typecode> h is already used on target! 


Error: The target reports that there is already a PC element using the <typecode> specified for 
the option that was currently to be loaded. Check whether the type code has a value in the range 
from 0x400 to 0x500 and whether there are already options using the same type code. 


Image file version incompatible to loader. 


Error: You are trying to load a newer version of image file than this loader was created for. 
Make sure to use an Image Loader that fits to the version of the Image Builder. 


Insufficient free memory for download of library. 


Error: The target reported that the code of the image does not fit either into RAM or into the 
system software FPROM. Decrease the size of the image. 


Library is already installed on target. 


Error: The target reported that the library with name specified in Image Builder command file 
already is installed. De-install the library or specify another name in command file. 


No valid option code to load. 


Error: The Image Loader was not able to find any or the entire code for the option that was to be 
loaded. Make sure that the image file is not corrupt. 


Option not available on target machine! 


Error: It was not possible to delete the specified library since the target reported that it is not 
present. 


Unexpected error during creation of library (<errorcode> h). 


Error: AC 160 reported an error (<errorcode>). The Loading of the library was aborted. It is 
possible to restart the target since the system software has not been erased so far. 
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Unknown error code <errorcode>! 


Error: An unknown error code <errorcode> was reported by AC 160 during deletion of the 
library. 


Wrong target type - target is: >targetname1<, Library requires: >targetname2< 


Error: The library that shall be loaded was made for another target. The loader expected 
targetname? but is connected to targetname!. Make sure that the correct target is connected or 
specify another target (© TARGET) in the Image Builder command file. 
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Appendix A Sample Option “POWER” 


A.1 Introduction 


A.2 Layout 


This chapter describes briefly how the sample option “POWER” with a single PC element 
POWER looks like, and how this option is distributed to AMPL Control Configuration (ACC) 
and Advant Controller 110 2.2. We assume that the image file for Advant Controller 110 2.2 
exists and has been created as explained in Chapter 4, and focus on the description files for 
ACC. 


The PC element “POWER?” in our example shall have the layout shown below: 


POWER 
—l— VALUE RESULT f--2 - 


ERR}-3 - 


Figure A-1. Layout of PC Element “POWER“ in FCB 


A.3 Description Files for AMPL Control Configuration 


A.3.1 PC Element Description File 
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After having fixed the layout, the PC Element Description file (*.PED) is written with a 
standard ASCI-text editor. 


How the PC element description is designed, is documented thoroughly in AMPL Control 
Configuration PC Element Description for Advant Controller 100 Series, Designer’s Guide. 


The PED-file may contain several PC element definitions. Thus, a file name should be chosen 
that indicates common functionality. Since in our example only one PC element is defined, the 
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—_> LIBIYPE 
—_——- LIBNAME 
—_——> LIBVERSION 


— 


file name is “POWER.PED”. The following figure shows the content of the complete file with 


brief remarks. 


PUTGETPLANNINGTYPE 


TYPCODE 


4 FUNCM 


——> LEVEL 1 


terminal 
_—> 


terminal 
terminal 


—> end Pow! 


pc_element 


ER; 


Ws 
"POWER 
:= "1.0/0 


—_— > PCc_element POWER 
_ 
_ NOBYTESHISTORIC 
COMPUTINGTIME := 400; 
NONEXECUTABLE 


:= H’0404; 


BLOCK CONT 
"POWER"; 


1 name "VALUI 
2 name "RI 


3 name "E 


XYZ 


We 
1, 


We 
, 


RM 


ESULT" type OUT I OFFSE 


RR" 


normal; 


r=1:0% 


SLAVEM ST 


EP; 


type OUT 


(* more definitions *) 


end XYZ; 


E" type IN I OFFSET 


B OFFSET 


Figure A-2. PED-File for PC Element “POWER” 


Entries with arrows are to be defined or modified by the developer; other entries are fixed for 
Advant Controller 100 Series. 


LIBTYPE 


For Advant Controller 100 Series, this is always “3”. 


LIBNAME / LIBVERSION 


This library strings are displayed in Application Builder (APB) as “available” or “selected” 
option after set up of the add-on library. 
Both strings must match those in the BLD-file for Image Builder. After loading the library to the 
target, the strings are displayed in “Report Options” dialog. 


PUTGETPLANNINGTYPE 


For Advant Controller 100 Series, this is always “normal”. 
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TYPCODE 


This value has to be the same as specified in ODF-file. It defines, which type code has to be 
inserted when generating target code for this element. 


NOBYTESHISTORIC 


Defines the amount of bytes to reserve as historical data. The value must match the memory 
requirements on the Controller. 


COMPUTINGTIME 


This entry allows inserting a value for the computing time of the PC element on target (in micro 
seconds). Since this may vary in dependency of call parameters, formulas are allowed. The 
value is used by AS 100ES to compute the system load of the application. 


LEVEL 1 <PC element display name> 


This entry defines the string that is to be displayed in function chart and tree view. 


terminal <tVal> name <tString> type <dir> <data type> OFFSET := <offset> 
This instruction defines the terminal; each terminal needs it’s own instruction. 


—  <tVal>: 
This value is the terminal number displayed in function chart view. 


—  <tString>: 
This string is the terminal name displayed in function chart view. It’s size is limited to 
8 characters. 


— <dir>: 
This value defines the direction of data flow: “I’ defines an input value, “O” an 
output value; 


—  <data type>: 
This value specifies the data type of the terminal: “B” - Master BOOLEAN; “T” - 
Integer (16 bit); “IL” - Integer Long (32 bit); “R” - Real Value; “T” - Time Value; 
“TR” - Time Real. 


- <offset>: 


This value specifies the offset of the terminal within the object code structure. 


CAUTION 


The PC element developer has to calculate all offsets “by hand”. Incorrect offsets 
may destroy data of other PC elements. The object code structure members in C- 
language PC element code must be located at exactly the same offsets. 
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The calculation in our example shall be explained by this table using two different PC 
element layouts: our example “POWER” and another example with two call 
parameters and one function parameter: 


Table A-1. Offset Calculation for PC Element 


Object Code Member praca cities age ete 
TYPCODE 0 0 
SIZE (of object code structure) 2 2 
Offset to Historical Data 4 4 
Call Parameter 1 not present 6 
Call Parameter 2 not present 7 
Function Parameter 1 not present 8 
Dummy not necessary 9 
Terminal 1 6 10 
Terminal 2 8 12 
Terminal 3 10 14 

NOTE 


All offset entries, e.g. to historical data or terminal values, have a size of 16 bit 
(WORD). They are not related to the data type which the terminal is assigned to. 


A.3.2 Target Description File 
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After definition of all PC elements that shall belong to one library, the Target Element 
Description file (*. TED) can be created using a standard ASCII text editor. This file describes 
how the new PC elements are to be integrated into an existing target. For details see AMPL 
Control Configuration Setup Add-ons Designer's Guide. 
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The following figure shows the content of the complete file: 


syntax 1.1; 


modify target "AC 110" version 2.2; 


add 


option "POWER" version 3.0/0; 
comment "PC element power"; 
supports 
pc_element library power version 1.0/0 stored in power; 


end_option; 


A.4 Image File 


Figure A-3. TED-File for Option “POWER” 


NOTE 


In this example, Advant Controller 110 version 2.2 is selected as target. You may 
wish to adjust the TED-file to another target, e.g., Advant Controller 70 or 
Advant Controller 160. 


Described in Chapter 4, How to Build an Option. 


A.5 Distribution Disk 


Create a distribution disk for option POWER which contains the following files: 


LOADER32.EXE 
32-bit option loader working under Windows NT 4.0 


POWER.IMG 
the image file to be loaded to Advant Controller 110. 


POWER.BAT 
Batch file to automatically invoke the loader with the image file. 


POWER.TED 
Target description file for AMPL Control Configuration. 


POWER.PED 
PC element description file for AMPL Control Configuration. 


README.TXT 
Distribution information. 


The option can either be installed directly from the diskette or the files can be copied manually 
to the local hard disk. 
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A.6 Loading the Option to the Controller 


Connect your AS 100ES (or standard PC) to the serial interface for Tools of the Processor 
Module. This is either labelled “CH1” or “Com A” depending on the type of Processor Module. 
You can use the same cable that is used to connect Function Chart Builder to the Processor 
Module. 


For our sample option “POWER”, you need to connect to a PM632, PM633, or PM634 with 
Advant Controller 110 2.2 system software being loaded. 


Insert the “POWER option” distribution diskette into the your PC and use Windows NT 
Explorer to browse to the the diskette drive. Now load the option to the Processor Module by 
double-clicking POWER.BAT. The loader pops up and the loading process starts automatically. 


NOTE 


You may need to select the correect serial interface (COM1, COM2, ...) on your 
PC before loading. 


A.7 Adding the Option to AMPL Control Configuration 
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It is assumed that you have an Advant Station 100 Series Engineering Station or a standard PC 
with or a standard PC with AMPL Control Configuration 1.7 or higher installed, and AMPL PC 
and DB Libraries 1.3 or higher. 


Insert the “POWER option” distribution diskette into drive A:, press the Start button and select 
Advant | Engineering | Utilities | Setup Add-ons 4.7-0. 


Choose “copy and compile” and check “replace destination files”, then click OK. Browse to the 
diskette drive and click Open. The option is now being installed for AMPL Control 
Configuration. 


If you now create a new node of type “AC 110 2.2”, Application Builder should offer under 
“available options” our sample option “POWER 3.0/0”. 


If you have an existing node of type “AC 110 2.2”, then the new option becomes available after 
selecting the node in Application Builder and pressing the modify... button. 


Start Function Chart Builder on the AC 110 2.2 node and verify that PC element Power is 
available. 
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